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Message Encryption for Web Push 
Abstract 
This document describes a message encryption scheme for the Web Push 
protocol. This scheme provides confidentiality and integrity for 
messages sent from an application server to a user agent. 
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1. Introduction 


The Web Push protocol [RFC8030] is an intermediated protocol by 
necessity. Messages from an application server are delivered to a 
user agent (UA) via a push service, as shown in Figure 1. 


| 
| Setup | | 
| 


Figure 1 
This document describes how messages sent using this protocol can be 


secured against inspection, modification, and forgery by a push 
service. 
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Web Push messages are the payload of an HTTP message [RFC7230]. 
These messages are encrypted using an encrypted content encoding 
[RFC8188]. This document describes how this content encoding is 
applied and describes a recommended key management scheme. 


Multiple users of Web Push at the same user agent often share a 
central agent that aggregates push functionality. This agent can 
enforce the use of this encryption scheme by applications that use 
push messaging. An agent that only delivers messages that are 
properly encrypted strongly encourages the end-to-end protection of 
messages. 


A web browser that implements the Push API [API] can enforce the use 
of encryption by forwarding only those messages that were properly 
encrypted. 


1.1. Notational Conventions 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 
"OPTIONAL" in this document are to be interpreted as described in BCP 
14 [RFC2119] [RFC8174] when, and only when, they appear in all 
capitals, as shown here. 


This document uses the terminology from [RFC8030], primarily "user 
agent", "push service", and "application server". 


2. Push Message Encryption Overview 


Encrypting a push message uses Elliptic Curve Diffie-Hellman (ECDH) 
[ECDH] on the P-256 curve [FIPS186] to establish a shared secret (see 
Section 3.1) and a symmetric secret for authentication (see 

Section 3.2). 


A user agent generates an ECDH key pair and authentication secret 
that it associates with each subscription it creates. The ECDH 
public key and the authentication secret are sent to the application 
server with other details of the push subscription. 


When sending a message, an application server generates an ECDH key 
pair and a random salt. The ECDH public key is encoded into the 
"keyid" parameter of the encrypted content coding header, and the 
salt is encoded into the "salt" parameter of that same header (see 
Section 2.1 of [RFC8188]). The ECDH key pair can be discarded after 
encrypting the message. 
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The content of the push message is encrypted or decrypted using a 
content encryption key and nonce. These values are derived by taking 
the "keyid" and "salt" as input to the process described in 

Section 3. 


2.1. Key and Secret Distribution 


The application using the subscription distributes the subscription 
public key and authentication secret to an authorized application 
server. This could be sent along with other subscription information 
that is provided by the user agent, such as the push subscription 
URI. 


An application MUST use an authenticated, confidentiality-protected 
communications medium for this purpose. In addition to the reasons 
described in [RFC8030], this use ensures that the authentication 
secret is not revealed to unauthorized entities, which would allow 
those entities to generate push messages that will be accepted by the 
user agent. 


Most applications that use push messaging have a preexisting 
relationship with an application server that can be used for 
distribution of subscription data. An authenticated communication 
mechanism that provides adequate confidentiality and integrity 
protection, such as HTTPS [RFC2818], is sufficient. 


3. Push Message Encryption 
Push message encryption happens in four phases: 


o A shared secret is derived using ECDH [ECDH] (see Section 3.1 of 
this document). 


o The shared secret is then combined with the authentication secret 
to produce the input keying material (IKM) used in [RFC8188] (see 


Section 3.3 of this document). 


o A content encryption key and nonce are derived using the process 
in [RFC8188]. 


o Encryption or decryption follows according to [RFC8188]. 
The key derivation process is summarized in Section 3.4. 


Restrictions on the use of the encrypted content coding are described 
in Section 4. 
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3.1. Diffie-Hellman Key Agreement 


For each new subscription that the user agent generates for an 
application, it also generates a P-256 [FIPS186] key pair for use in 
ECDH [ECDH]. 


When sending a push message, the application server also generates a 
new ECDH key pair on the same P-256 curve. 


The ECDH public key for the application server is included as the 
"keyid" parameter in the encrypted content coding header (see 
Section 2.1 of [RFC8188]). 


An application server combines its ECDH private key with the public 
key provided by the user agent using the process described in [ECDH]; 
on receipt of the push message, a user agent combines its private key 
with the public key provided by the application server in the "keyid" 
parameter in the same way. These operations produce the same value 
for the ECDH shared secret. 


3.2. Push Message Authentication 


To ensure that push messages are correctly authenticated, a symmetric 
authentication secret is added to the information generated by a user 
agent. The authentication secret is mixed into the key derivation 
process described in Section 3.3. 


A user agent MUST generate and provide a hard-to-guess sequence of 16 


octets that is used for authentication of push messages. This SHOULD 
be generated by a cryptographically strong random number generator 
[RFC4086]. 

3.3. Combining Shared and Authentication Secrets 


The shared secret produced by ECDH is combined with the 
authentication secret using the HMAC-based key derivation function 
(HKDF) [RFC5869]. This produces the input keying material used by 
[RFC8188]. 


The HKDF function uses the SHA-256 hash algorithm [FIPS180-4] with 
the following inputs: 


salt: the authentication secret 


IKM: the shared secret derived using ECDH 
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info: the concatenation of the ASCII-encoded string "WebPush: info" 
(this string is not NUL-terminated), a zero octet, the user 
agent ECDH public key, and the application server ECDH public 
key, (both ECDH public keys are in the uncompressed point form 
defined in [X9.62]. That is: 
key_info = "WebPush: info" || 0x00 || ua_public || as_public 
L: 32 octets (i.e., the output is the length of the underlying 
SHA-256 HMAC function output) 
3.4. Encryption Summary 
This results in a final content encryption key and nonce generation 
using the following sequence, which is shown here in pseudocode with 
HKDF expanded into separate discrete steps using HMAC with SHA-256: 
-- For a user agent: 
ecdh_secret = ECDH(ua_private, as_public) 
auth_secret = random(16) 
salt = <from content coding header> 
-- For an application server: 
ecdh_secret = ECDH(as_private, ua_public) 
auth_secret = <from user agent> 
salt = random(16) 
== For both: 
## Use HKDF to combine the ECDH and authentication secrets 
# HKDF-Extract (salt=auth_secret, IKM=ecdh_secret) 


PRK_key = HMAC-SHA-256(auth_secret, ecdh_secret) 


+ H 


KDF-Expand (PRK_key, key_info, L_key=32) 


key_info = "WebPush: info" || 0x00 || ua public || as_public 


IKM 


Ht 
+ E 
PRK 
# H 


cek_info = "Content-Encoding: aes128gcm" 


CEK 
+ H 
non 
NON 


Thomson 


= HMAC-SHA-256(PRK_key, key_info || 0x01) 


HKDF calculations from RFC 8188 
KDF-Extract (salt, IKM) 
= HMAC-SHA-256(salt, IKM) 
KDF-Expand(PRK, cek_info, L_cek=16) 
|| 0x00 
= HMAC-SHA-256 (PRK, cek_info || 0x01) [0..15] 
KDF-Expand (PRK, nonce_info, L_nonce=12) 
ce_info = "Content-Encoding: nonce" | | 0x00 
CE = HMAC-SHA-256(PRK, nonce_info || 0x01) [0..11] 
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Note that this omits the exclusive-OR of the final nonce with the 
record sequence number, since push messages contain only a single 
record (see Section 4) and the sequence number of the first record is 
zero. 


4. Restrictions on Use of "aes128gcm" Content Coding 


An application server MUST encrypt a push message with a single 
record. This allows for a minimal receiver implementation that 
handles a single record. An application server MUST set the "rs" 
parameter in the "aes128gcm" content coding header to a size that is 
greater than the sum of the lengths of the plaintext, the padding 
delimiter (1 octet), any padding, and the authentication tag (16 
octets). 


A push message MUST include the application server ECDH public key in 
the "keyid" parameter of the encrypted content coding header. The 


uncompressed point form defined in [X9.62] (that is, a 65-octet 
sequence that starts with a 0x04 octet) forms the entirety of the 
"keyid". Note that this means that the "keyid" parameter will not be 


valid UTF-8 as recommended in [RFC8188]. 


A push service is not required to support more than 4096 octets of 
payload body (see Section 7.2 of [RFC8030]). Absent header (86 
octets), padding (minimum 1 octet), and expansion for 
AEAD_AES_128_GCM (16 octets), this equates to, at most, 3993 octets 
of plaintext. 


An application server MUST NOT use other content encodings for push 
messages. In particular, content encodings that compress could 
result in leaking of push message contents. The Content-Encoding 
header field therefore has exactly one value, which is "aes128gcm". 
Multiple "aes128gcm" values are not permitted. 


A user agent is not required to support multiple records. A user 
agent MAY ignore the "rs" parameter. If a record size is unchecked, 
decryption will fail with high probability for all valid cases. The 
padding delimiter octet MUST be checked; values other than 0x02 MUST 
cause the message to be discarded. 


Thomson Standards Track [Page 7] 


RFC 8291 Web Push Encryption November 2017 


3% 


Push Message Encryption Example 


The following example shows a push message being sent to a push 
service. 


POST /push/JzLO3raZJfFBROaqvOMsLrt54w4rJUsV HTTP/1.1 
Host: push.example.net 

TTL: 10 

Content-Length: 145 

Content-Encoding: aes128gcm 


DGv6ralnlYgDCS1FRnbz1wAAEABBBP4z9KsN6nGRTIbVYI_c7VJSPOTBtkgcy27m1 
m1lMoZIIgD116e3vCYLocInmYWAmS 6T1zAC8wEQKK6PBru3j17A_yl195bQpu6cVPT 
pK4Mqgkf£1CXztLVBSt2Ks30ZwbuwXPXLWyouBWLVWGNWOQexSgSxsj_Qulcy4a-f£N 


This example shows the ASCII-encoded string, "When I grow up, I want 
to be a watermelon". The content body is shown here with line 
wrapping and URL-safe base64url [RFC4648] encoding to meet 
presentation constraints. 


The keys used are shown below using the uncompressed form [X9.62] 
encoded using base64url. 


Authentication Secret: BTBZMqHH6r4Tts7J_aSIgg 
Receiver: 
private key: qldXpw3UpT5VOmu_cf_v6ih07Aems3njxI-JWgLcM94 
public key: BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhquzORcx 
aOzi6—-AYWXvTBHm4b jyP js 7Vd8pZGH6SRpkNt olIAiw4 
Sender: 
private key: yfWPiYE-n46HLnHOKqZOF1£JJU3MYrct 3AELtAQ-oRw 
public key: BP4z9KsN6nGRTbVYI_c7VJISPOTBtkgcy27mlm1MoZIIg 
D116e3vCYLocInmYWAmS6T1zAC8wEqkKK6PBru3317A8 


Intermediate values for this example are included in Appendix A. 
IANA Considerations 

This document does not require any IANA actions. 

Security Considerations 


The privacy and security considerations of [RFC8030] all apply to the 
use of this mechanism. 


The Security Considerations section of [RFC8188] describes the 
limitations of the content encoding. In particular, no HTTP header 
fields are protected by the content encoding scheme. A user agent 
MUST consider HTTP header fields to have come from the push service. 
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Though header fields might be necessary for processing an HTTP 
response correctly, they are not needed for correct operation of the 
protocol. An application on the user agent that uses information 
from header fields to alter their processing of a push message is 
exposed to a risk of attack by the push service. 


The timing and length of communication cannot be hidden from the push 
service. While an outside observer might see individual messages 
intermixed with each other, the push service will see which 
application server is talking to which user agent and the 
subscription that is used. Additionally, the length of messages 
could be revealed unless the padding provided by the content encoding 
scheme is used to obscure length. 


The user agent and application MUST verify that the public key they 
receive is on the P-256 curve. Failure to validate a public key can 
allow an attacker to extract a private key. The appropriate 
validation procedures are defined in Section 4.3.7 of [X9.62] and, 
alternatively, in Section 5.6.2.3 of [KEYAGREEMENT]. This process 
consists of three steps: 


1. Verify that Y is not the point at infinity (0), 


2. Verify that for Y = (x, y), both integers are in the correct 
interval, 

3. Ensure that (x, y) is a correct solution to the elliptic curve 
equation. 


For these curves, implementers do not need to verify membership in 
the correct subgroup. 


In the event that this encryption scheme would need to be replaced, a 
new content coding scheme could be defined. In order to manage 
progressive deployment of the new scheme, the user agent can expose 
information on the content coding schemes that it supports. The 
"supportedContentEncodings" parameter of the Push API [API] is an 
example of how this might be done. 
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Appendix A. Intermediate Values for Encryption 
The intermediate values calculated for the example in Section 5 are 
shown here. The base64url values in these examples include 
whitespace that can be removed. 
The following are inputs to the calculation: 
Plaintext: V2h1biBJIGdyb3cgdXAslIEkgd2FudCBObyBiZSBhIHdhdGVybWVsb24 
Application server public key (as_public): 


BP4z9KsN6nGRTIbVYI_c7VISPQOTBtkgcy27mlm1MoZIIg 
D116e3vCYLocInmYWAmS6T1zAC8wEqKK6PBru3317A8 


Application server private key (as_private): 
yfWPiYE-n46HLnHOKqzOF1fJJU3MYrct 3AELtAQ-oRw 


User agent public key (ua_public): BCVxsr7N_eNgVRqvHtDOzTZsEc6-VV- 
JvLexhqUzORcx aO0zi6-AYWXvTBHm4b3yP3js7Vd8pZGH6SRPkNtoIAiw4 


User agent private key (ua_private): 
aldXpw3UpT5VOmu_cf_v6ih07Aems3n3xI-JWgLcM94 


Salt: DGv6ralnlYgDCS1FRnbzlw 

Authentication secret (auth_secret): BTBZMqHH6r4Tts7J_aSlgg 
Note that knowledge of just one of the private keys is necessary. 
The application server randomly generates the salt value, whereas 
salt is input to the receiver. 


This produces the following intermediate values: 


Shared ECDH secret (ecdh_secret): 
kyrL1jJIIOHEzg3sM2ZWRHDRB62YACZhhS1knJ672kSs 


Pseudorandom key (PRK) for key combining (PRK_key) : 
Snr3JMxaHVDXHWJn5wdC52W3jpCtd2ETEGBykDcZW32k 


Info for key combining (key_info): V2ViUHVzaDogaW5mbwAEJXGyvs3942BVG 
q8eOPTNNmwR zr5VX4m8t 7GGpTM5FzFo7OLr4BhZe9MEebhuPI-0OztV3 
ylkYfpJGmO22ggCLDgT-M_SrDepxkU21WCP301SUj0Ew 
bZIHMtu5pZpTKGSCIA5Zent 7wmC6HCISmF gJkuk5ScwAv MBKiiujwa7t45ewP 


Input keying material for content encryption key derivation (IKM): 
S41YMb_LOFxCeqOWhDx813KgSYqU26kOyzWUdsxXYyrg 
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PRK for content encryption (PRK): 
09_eUZGrsvxChDCGRCdkLiDXrReGOEVeSCdCcPBSJSc 


Info for content encryption key derivation (cek_info): 
Q2 9udGVudC1FbmNvZGluZzogYWVzMTI4Z2NtAA 


Content encryption key (CEK): oIhVWO4MRdy2XN9CiKLxTg 


Info for content encryption nonce derivation (nonce_info): 
Q2 9udGVudC1FbmNvZGluZzogbm9uY2UA 


Nonce (NONCE): 4h_95k1XJ5E_qnoN 


The salt, record size of 4096, and application server public key 
produce an 86-octet header of: 


DGv6raln1YgDCS1FRnbzlwAAEABBBP4z 9KSN6nGRTbVYI_c7VISPOTBtkgcy27m1 
m1MoZIIgD116e3vCYLocInmYWAmS6T1z AC8wEQqKK6PBru3j17A8 


The push message plaintext has the padding delimiter octet (0x02) 
appended to produce: 


V2h1biBJIGdyb3cgdXAsIEkgd2FudCBO byBiZSBhIHdhdGVybWVsb24C 


The plaintext is then encrypted with AES-GCM, which emits ciphertext 
of: 


8pfeW0KbunFTO6SUDKoJH90187S1QUrd irN6GcG7sFz1ly1sqLgVilVhjVkHsUoEs 
bI_OLpXMuGvnzQ 


The header and ciphertext are concatenated and produce the result 
shown in Section 5. 
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